Inside Macintosh: Imaging with QuickDraw
Color QuickDraw uses GDevice records to maintain information about video devices and offscreen graphics worlds. A GDevice record must be allocated with the NewGDevice function and initialized with the InitGDevice procedure. Normally, your application does not call these routines directly. When the system starts up, it allocates and initializes one handle to a GDevice record for each video device it finds. When you use the NewGWorld function (described in the chapter "Offscreen Graphics Worlds" in this book), Color QuickDraw automatically creates a GDevice record for the new offscreen graphics world.
Whenever QuickDraw routines are used to draw into a graphics port on a video device, Color QuickDraw uses the SetGDevice procedure to make the video device for that screen the current device. Your application won't generally need to use this procedure, because when your application draws into a window on one or more screens, Color QuickDraw automatically switches GDevice records as appropriate; and when your application needs to draw into an offscreen graphics world, it can use the SetGWorld procedure to set the graphics port as well as the GDevice record for the offscreen environment. However, if your application uses the SetPort procedure (described in the chapter "Basic QuickDraw" in this book) instead of the SetGWorld procedure to set the graphics port to or from an offscreen graphics world, then your application must use SetGDevice in conjunction with SetPort .
You use the SetDeviceAttribute procedure to set attribute bits in a GDevice record.
When Color QuickDraw no longer needs a GDevice record, it uses the DisposeGDevice procedure to dispose of it. As with the other routines described in this section, your application typically does not need to use DisposeGDevice .
You can use the NewGDevice function to create a new GDevice record, although you generally don't need to, because Color QuickDraw uses this function to create GDevice records for your application automatically.
FUNCTION NewGDevice (refNum: Integer; mode: LongInt): GDHandle;
For the graphics device whose driver is specified in the refNum parameter and whose mode is specified in the mode parameter, the NewGDevice function allocates a new GDevice record and all of its handles, and then calls the InitGDevice procedure to initialize the record. As its function result, NewGDevice returns a handle to the new GDevice record. If the request is unsuccessful, NewGDevice returns NIL .
The NewGDevice function allocates the new GDevice record and all of its handles in the system heap, and the NewGDevice function sets all attributes in the gdFlags field of the GDevice record to FALSE . If your application creates a GDevice record, it can use the SetDeviceAttribute procedure, described on SetDeviceAttribute , to change the flag bits in the gdFlags field of the GDevice record to TRUE . Your application should never directly change the gdFlags field of the GDevice record; instead, your application should use only the SetDeviceAttribute procedure.
If your application creates a GDevice record without a driver, it should set the mode parameter to -1. In this case, InitGDevice cannot initialize the GDevice record, so your application must perform all initialization of the record. A GDevice record's default mode is defined as 128; this is assumed to be a black-and-white mode. If you specify a value other than 128 in the mode parameter, the record's gdDevType bit in the gdFlags field of the GDevice record is set to TRUE to indicate that the graphics device is capable of displaying color.
The NewGDevice function doesn't automatically insert the GDevice record into the device list. In general, your application shouldn't create GDevice records, and if it ever does, it should never add them to the device list.
If your program uses NewGDevice to create a graphics device without a driver, InitGDevice does nothing; instead, your application must initialize all fields of the GDevice record. After your application initializes the color table for the GDevice record, your application should call the Color Manager procedure MakeITable to build the inverse table for the graphics device.
The NewGDevice function may move or purge memory blocks in the application heap. Your application should not call this function at interrupt time.
The GDevice record is described on GDevice . See Designing Cards and Drivers for the Macintosh Family , third edition, for more information about the device modes that you can specify in the mode parameter. The Color Manager is described in Inside Macintosh: Advanced Color Imaging .
The NewGDevice function uses the InitGDevice procedure to initialize a GDevice record.
PROCEDURE InitGDevice (gdRefNum: Integer; mode: LongInt;
gdh: GDHandle);
The InitGDevice procedure initializes the GDevice record specified in the gdh parameter. The InitGDevice procedure sets the graphics device whose driver has the reference number specified in the gdRefNum parameter to the mode specified in the mode parameter. The InitGDevice procedure then fills out the GDevice record, previously created with the NewGDevice function, to contain all information describing that mode.
The mode parameter determines the configuration of the device; possible modes for a device can be determined by interrogating the video device's ROM through Slot Manager routines. The information describing the device's mode is primarily contained in the video device's ROM. If the video device has a fixed color table, then that table is read directly from the ROM. If the video device has a variable color table, then InitGDevice uses the default color table defined in a 'clut' resource, contained in the System file, that has a resource ID equal to the video device's pixel depth.
In general, your application should never need to call InitGDevice . All video devices are initialized at start time, and users change modes through the Monitors control panel.
If your program uses NewGDevice to create a graphics device without a driver, InitGDevice does nothing; instead, your application must initialize all fields of the GDevice record. After your application initializes the color table for the GDevice record, your application should call the Color Manager procedure MakeITable to build the inverse table for the graphics device.
The InitGDevice procedure may move or purge memory blocks in the application heap. Your application should not call this procedure at interrupt time.
The GDevice record is described on GDevice . See Designing Cards and Drivers for the Macintosh Family , third edition, for more information about the device modes that you can specify in the mode parameter. The MakeITable procedure is described in the chapter "Color Manager" in Inside Macintosh: Advanced Color Imaging .
To set the attribute bits of a GDevice record, use the SetDeviceAttribute procedure.
PROCEDURE SetDeviceAttribute (gdh: GDHandle; attribute: Integer;
value: Boolean);
CONST {flag bits for gdFlags field of GDevice record}
gdDevType = 0; {if bit is set to 0, graphics }
{ device is black and white; }
{ if set to 1, device supports }
{ color}
burstDevice = 7; {if bit is set to 1, device }
{ supports block transfer}
ext32Device = 8; {if bit is set to 1, device }
{ must be used in 32-bit mode}
ramInit = 10; {if bit is set to 1, device has }
{ been initialized from RAM}
mainScreen = 11; {if bit is set to 1, device is }
{ the main screen}
allInit = 12; {if bit is set to 1, all }
{ devices were initialized from }
{ 'scrn' resource}
screenDevice = 13; {if bit is set to 1, device is }
{ a screen}
noDriver = 14; {if bit is set to 1, GDevice }
{ record has no driver}
screenActive = 15; {if bit is set to 1, device is }
{ active}
For the graphics device specified in the gdh parameter, the SetDeviceAttribute procedure sets the flag bit specified in the attribute parameter to the value specified in the value parameter.
Your application should never directly change the gdFlags field of the GDevice record; instead, your application should use only the SetDeviceAttribute procedure.
The SetDeviceAttribute procedure may move or purge memory blocks in the application heap. Your application should not call this procedure at interrupt time.
Your application can use the SetGDevice procedure to set a GDevice record as the current device.
PROCEDURE SetGDevice (gdh: GDHandle);
The SetGDevice procedure sets the specified GDevice record as the current device. Your application won't generally need to use this procedure, because when your application draws into a window on one or more screens, Color QuickDraw automatically switches GDevice records as appropriate; and when your application needs to draw into an offscreen graphics world, it can use the SetGWorld procedure to set the graphics port as well as the GDevice record for the offscreen environment. However, if your application uses the SetPort procedure (described in the chapter "Basic QuickDraw" in this book) instead of the SetGWorld procedure to set the graphics port to or from an offscreen graphics world, then your application must use SetGDevice in conjunction with SetPort .
A handle to the currently active device is kept in the global variable TheGDevice .
Although your application generally should never need to use this routine, the DisposeGDevice procedure disposes of a GDevice record, releases the space allocated for it, and disposes of all the data structures allocated for it. The DisposeGDevice procedure is also available as the DisposGDevice procedure.
PROCEDURE DisposeGDevice (gdh: GDHandle);